---
toc_max_heading_level: 4
slug: /sidebar/items
---

# Sidebar items

```mdx-code-block
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import BrowserWindow from '@site/src/components/BrowserWindow';
```

The sidebar supports various item types:

- **[Doc](#sidebar-item-doc)**: link to a doc page, associating it with the sidebar
- **[Link](#sidebar-item-link)**: link to any internal or external page
- **[Category](#sidebar-item-category)**: creates a dropdown of sidebar items
- **[Autogenerated](autogenerated.mdx)**: generate a sidebar slice automatically
- **[HTML](#sidebar-item-html)**: renders pure HTML in the item's position
- **[Ref](multiple-sidebars.mdx#sidebar-item-ref)**: link to a doc page, without making the item take part in navigation generation

## Doc: link to a doc {#sidebar-item-doc}

Use the `doc` type to link to a doc page and assign that doc to a sidebar:

```ts
type SidebarItemDoc =
  // Normal syntax
  | {
      type: 'doc';
      id: string;
      label: string; // Sidebar label text
      key?: string; // Sidebar key to uniquely identify the item
      className?: string; // Class name for sidebar label
      customProps?: Record<string, unknown>; // Custom props
    }

  // Shorthand syntax
  | string; // docId shortcut
```

Example:

```js title="sidebars.js"
export default {
  mySidebar: [
    // Normal syntax:
    // highlight-start
    {
      type: 'doc',
      id: 'doc1', // document ID
      label: 'Getting started', // sidebar label
    },
    // highlight-end

    // Shorthand syntax:
    // highlight-start
    'doc2', // document ID
    // highlight-end
  ],
};
```

If you use the doc shorthand or [autogenerated](autogenerated.mdx) sidebar, you would lose the ability to customize the sidebar label through item definition. You can, however, use the `sidebar_label` Markdown front matter within that doc, which has higher precedence over the `label` key in the sidebar item. Similarly, you can use `sidebar_custom_props` to declare custom metadata for a doc page.

:::note

A `doc` item sets an [implicit sidebar association](./multiple-sidebars.mdx#sidebar-association). Don't assign the same doc to multiple sidebars: change the type to `ref` instead.

:::

:::tip

Sidebar custom props is a useful way to propagate arbitrary doc metadata to the client side, so you can get additional information when using any doc-related hook that fetches a doc object.

:::

## Link: link to any page {#sidebar-item-link}

Use the `link` type to link to any page (internal or external) that is not a doc.

```ts
type SidebarItemLink = {
  type: 'link';
  label: string;
  href: string;
  description?: string;
  key?: string;
  className?: string;
  customProps?: Record<string, unknown>;
};
```

Example:

```js title="sidebars.js"
export default {
  myLinksSidebar: [
    // highlight-start
    // External link
    {
      type: 'link',
      label: 'Facebook', // The link label
      href: 'https://facebook.com', // The external URL
    },
    // highlight-end

    // highlight-start
    // Internal link
    {
      type: 'link',
      label: 'Home', // The link label
      href: '/', // The internal path
    },
    // highlight-end
  ],
};
```

## HTML: render custom markup {#sidebar-item-html}

Use the `html` type to render custom HTML within the item's `<li>` tag.

This can be useful for inserting custom items such as dividers, section titles, ads, and images.

```ts
type SidebarItemHtml = {
  type: 'html';
  value: string;
  defaultStyle?: boolean; // Use default menu item styles
  key?: string;
  className?: string;
  customProps?: Record<string, unknown>;
};
```

Example:

```js title="sidebars.js"
export default {
  myHtmlSidebar: [
    // highlight-start
    {
      type: 'html',
      value: '<img src="sponsor.png" alt="Sponsor" />', // The HTML to be rendered
      defaultStyle: true, // Use the default menu item styling
    },
    // highlight-end
  ],
};
```

:::tip

The menu item is already wrapped in an `<li>` tag, so if your custom item is simple, such as a title, just supply a string as the value and use the `className` property to style it:

```js title="sidebars.js"
export default {
  myHtmlSidebar: [
    {
      type: 'html',
      value: 'Core concepts',
      className: 'sidebar-title',
    },
  ],
};
```

:::

## Category: create a hierarchy {#sidebar-item-category}

Use the `category` type to create a hierarchy of sidebar items.

```ts
type SidebarItemCategory = {
  type: 'category';
  label: string; // Sidebar label text.
  items: SidebarItem[]; // Array of sidebar items.
  description?: string;
  key?: string;
  className?: string;
  customProps?: Record<string, unknown>;

  // Category options:
  collapsible: boolean; // Set the category to be collapsible
  collapsed: boolean; // Set the category to be initially collapsed or open by default
  link: SidebarItemCategoryLinkDoc | SidebarItemCategoryLinkGeneratedIndex;
};
```

Example:

```js title="sidebars.js"
export default {
  docs: [
    {
      type: 'category',
      label: 'Guides',
      collapsible: true,
      collapsed: false,
      items: [
        'creating-pages',
        {
          type: 'category',
          label: 'Docs',
          items: ['introduction', 'sidebar', 'markdown-features', 'versioning'],
        },
      ],
    },
  ],
};
```

:::tip

Use the [**shorthand syntax**](#category-shorthand) when you don't need customizations:

```js title="sidebars.js"
export default {
  docs: {
    Guides: [
      'creating-pages',
      {
        Docs: ['introduction', 'sidebar', 'markdown-features', 'versioning'],
      },
    ],
  },
};
```

:::

### Category links {#category-link}

With category links, clicking on a category can navigate you to another page.

:::tip

Use category links to introduce a category of documents.

Autogenerated categories can use the [`_category_.yml`](./autogenerated.mdx#category-item-metadata) file to declare the link.

:::

#### Generated index page {#generated-index-page}

You can auto-generate an index page that displays all the direct children of this category. The `slug` allows you to customize the generated page's route, which defaults to `/category/[categoryName]`.

```js title="sidebars.js"
export default {
  docs: [
    {
      type: 'category',
      label: 'Guides',
      // highlight-start
      link: {
        type: 'generated-index',
        title: 'Docusaurus Guides',
        description: 'Learn about the most important Docusaurus concepts!',
        slug: '/category/docusaurus-guides',
        keywords: ['guides'],
        image: '/img/docusaurus.png',
      },
      // highlight-end
      items: ['pages', 'docs', 'blog', 'search'],
    },
  ],
};
```

See it in action on the [Docusaurus Guides page](/docs/category/guides).

:::tip

Use `generated-index` links as a quick way to get an introductory document.

:::

#### Doc link {#category-doc-link}

A category can link to an existing document.

```js title="sidebars.js"
export default {
  docs: [
    {
      type: 'category',
      label: 'Guides',
      // highlight-start
      link: {type: 'doc', id: 'introduction'},
      // highlight-end
      items: ['pages', 'docs', 'blog', 'search'],
    },
  ],
};
```

See it in action on the [i18n introduction page](../../../i18n/i18n-introduction.mdx).

#### Embedding generated index in doc page {#embedding-generated-index-in-doc-page}

You can embed the generated cards list in a normal doc page as well with the `DocCardList` component. It will display all the sidebar items of the parent category of the current document.

```md title="docs/sidebar/index.md"
import DocCardList from '@theme/DocCardList';

<DocCardList />
```

```mdx-code-block
<BrowserWindow>

import DocCardList from '@theme/DocCardList';

<DocCardList />

</BrowserWindow>
```

### Collapsible categories {#collapsible-categories}

We support the option to expand/collapse categories. Categories are collapsible by default, but you can disable collapsing with `collapsible: false`.

```js title="sidebars.js"
export default {
  docs: [
    {
      type: 'category',
      label: 'Guides',
      items: [
        'creating-pages',
        {
          type: 'category',
          // highlight-next-line
          collapsible: false,
          label: 'Docs',
          items: ['introduction', 'sidebar', 'markdown-features', 'versioning'],
        },
      ],
    },
  ],
};
```

To make all categories non-collapsible by default, set the `sidebarCollapsible` option in `plugin-content-docs` to `false`:

```js title="docusaurus.config.js"
export default {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          // highlight-next-line
          sidebarCollapsible: false,
        },
      },
    ],
  ],
};
```

:::note

The option in `sidebars.js` takes precedence over plugin configuration, so it is possible to make certain categories collapsible when `sidebarCollapsible` is set to `false` globally.

:::

### Expanded categories by default {#expanded-categories-by-default}

Collapsible categories are collapsed by default. If you want them to be expanded on the first render, you can set `collapsed` to `false`:

```js title="sidebars.js"
export default {
  docs: {
    Guides: [
      'creating-pages',
      {
        type: 'category',
        label: 'Docs',
        // highlight-next-line
        collapsed: false,
        items: ['markdown-features', 'sidebar', 'versioning'],
      },
    ],
  },
};
```

Similar to `collapsible`, you can also set the global configuration `options.sidebarCollapsed` to `false`. Individual `collapsed` options in `sidebars.js` will still take precedence over this configuration.

```js title="docusaurus.config.js"
export default {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          // highlight-next-line
          sidebarCollapsed: false,
        },
      },
    ],
  ],
};
```

:::warning

When a category has `collapsed: true` but `collapsible: false` (either through `sidebars.js` or through plugin configuration), the latter takes precedence and the category is still rendered as expanded.

:::

## Using shorthands {#using-shorthands}

You can express typical sidebar items without much customization more concisely with **shorthand syntaxes**. There are two parts to this: [**doc shorthand**](#doc-shorthand) and [**category shorthand**](#category-shorthand).

### Doc shorthand {#doc-shorthand}

An item with type `doc` can be simply a string representing its ID:

```mdx-code-block
<Tabs>
<TabItem value="Longhand">
```

```js title="sidebars.js"
export default {
  sidebar: [
    // highlight-start
    {
      type: 'doc',
      id: 'myDoc',
    },
    // highlight-end
  ],
};
```

```mdx-code-block
</TabItem>
<TabItem value="Shorthand">
```

```js title="sidebars.js"
export default {
  sidebar: [
    // highlight-start
    'myDoc',
    // highlight-end
  ],
};
```

```mdx-code-block
</TabItem>
</Tabs>
```

So it's possible to simplify the example above to:

```js title="sidebars.js"
export default {
  mySidebar: [
    {
      type: 'category',
      label: 'Getting Started',
      items: [
        // highlight-next-line
        'doc1',
      ],
    },
    {
      type: 'category',
      label: 'Docusaurus',
      items: [
        // highlight-start
        'doc2',
        'doc3',
        // highlight-end
      ],
    },
    {
      type: 'link',
      label: 'Learn more',
      href: 'https://example.com',
    },
  ],
};
```

### Category shorthand {#category-shorthand}

A category item can be represented by an object whose key is its label, and the value is an array of subitems.

```mdx-code-block
<Tabs>
<TabItem value="Longhand">
```

```js title="sidebars.js"
export default {
  sidebar: [
    // highlight-start
    {
      type: 'category',
      label: 'Getting started',
      items: ['doc1', 'doc2'],
    },
    // highlight-end
  ],
};
```

```mdx-code-block
</TabItem>
<TabItem value="Shorthand">
```

```js title="sidebars.js"
export default {
  sidebar: [
    // highlight-start
    {
      'Getting started': ['doc1', 'doc2'],
    },
    // highlight-end
  ],
};
```

```mdx-code-block
</TabItem>
</Tabs>
```

This permits us to simplify that example to:

```js title="sidebars.js"
export default {
  mySidebar: [
    // highlight-start
    {
      'Getting started': ['doc1'],
    },
    {
      Docusaurus: ['doc2', 'doc3'],
    },
    // highlight-end
    {
      type: 'link',
      label: 'Learn more',
      href: 'https://example.com',
    },
  ],
};
```

Each shorthand object after this transformation will contain exactly one entry. Now consider the further simplified example below:

```js title="sidebars.js"
export default {
  mySidebar: [
    // highlight-start
    {
      'Getting started': ['doc1'],
      Docusaurus: ['doc2', 'doc3'],
    },
    // highlight-end
    {
      type: 'link',
      label: 'Learn more',
      href: 'https://example.com',
    },
  ],
};
```

Note how the two consecutive category shorthands are compressed into one object with two entries. This syntax generates a **sidebar slice**: you shouldn't see that object as one bulk item—this object is unwrapped, with each entry becoming a separate item, and they spliced together with the rest of the items (in this case, the "Learn more" link) to form the final sidebar level. Sidebar slices are also important when discussing [autogenerated sidebars](autogenerated.mdx).

Wherever you have an array of items that is reduced to one category shorthand, you can omit that enclosing array as well.

```mdx-code-block
<Tabs>
<TabItem value="Before">
```

```js title="sidebars.js"
export default {
  sidebar: [
    {
      'Getting started': ['doc1'],
      Docusaurus: [
        {
          'Basic guides': ['doc2', 'doc3'],
          'Advanced guides': ['doc4', 'doc5'],
        },
      ],
    },
  ],
};
```

```mdx-code-block
</TabItem>
<TabItem value="After">
```

```js title="sidebars.js"
export default {
  sidebar: {
    'Getting started': ['doc1'],
    Docusaurus: {
      'Basic guides': ['doc2', 'doc3'],
      'Advanced guides': ['doc4', 'doc5'],
    },
  },
};
```

```mdx-code-block
</TabItem>
</Tabs>
```
